gh-61745: Clarify os.listdir behavior for empty path#145338
gh-61745: Clarify os.listdir behavior for empty path#145338u-wlkjyy wants to merge 1 commit intopython:mainfrom
Conversation
|
All commit authors signed the Contributor License Agreement. |
bedevere-app
bot
added
awaiting review
docs
| If a file is removed from or added to the directory during the call of | ||
| this function, whether a name for that file be included is unspecified. | ||
| *path* must refer to an existing directory. Passing ``''`` raises | ||
| :exc:`FileNotFoundError`; use ``'.'`` to list the current directory. |
There was a problem hiding this comment.
I would prefer to suggest omitting the path argument to list the current directory.
There was a problem hiding this comment.
Thanks for the suggestion. I’d prefer to keep '.' in the docs here.
Omitting the argument is a convenience specific to os.listdir(), while '.' is the explicit path value used across many path APIs. Keeping '.' also makes the contrast with '' clearer: '' raises FileNotFoundError, but '.' means the current directory.
For example, developers explicitly use os.stat('.'), os.path.abspath('.'), and pathlib.Path('.') to refer to the current directory. In those APIs, you can’t express the same intent by omitting an argument. Using '.' here reduces context switching and avoids confusion for readers.
3 participants
Fixes gh-61745.
Clarify the
os.listdir()docs to explicitly state that passing an emptystring (
'') raisesFileNotFoundError, and that'.'should be usedfor the current directory.
This change updates documentation only.
📚 Documentation preview 📚: https://cpython-previews--145338.org.readthedocs.build/